.\" man page for __PACKAGE_NAME__
.TH __PACKAGE_NAME_UPPER___VOL_KEY 1 __TODAY__ "__PACKAGE_NAME__ __PACKAGE_VERSION__" "__PACKAGE_NAME___vol_key"

.SH NAME
\fB__PACKAGE_NAME___vol_key\fR - Manage __PACKAGE_NAME__ volume keys

.SH SYNOPSIS
\fB__PACKAGE_NAME___vol_key\fR
[\fB-c | --config-file\fR \fIpath\fR]
[\fB-i | --in-key\fR \fIpath\fR]
[\fB-o | --out-key\fR \fIpath\fR]
\fIcommand\fR

.SH DESCRIPTION
\fB__PACKAGE_NAME___vol_key\fR manages volume keys used for \fB__PACKAGE_NAME__\fR file encryption.
Operations will take place on the bucket specified by the default configuration
file (or the configuration file specified by \fB--config-file\fR) -- see
\fB__PACKAGE_NAME__.conf\fR(5).

.SH COMMANDS
.TP
.B list
List all bucket volume keys.

.TP
.BI "generate " "key-id"
Generate a volume key with the specified key identifier. This key will be
encrypted with a user-supplied password (read from standard input).  If
\fB--out-key\fR is specified, no password prompt will be presented, and the key
will be stored in the path specified by \fIpath\fR (this key file can then be
used to mount the encrypted bucket without prompting for a password). This
operation will fail if the bucket contains any volume keys. The \fB--in-key\fR
option is not valid with this command.

.TP
\fBclone\fR \fIcurrent-key-id\fR \fInew-key-id\fR
Copy \fIcurrent-key-id\fR to \fInew-key-id\fR. This permits access to encrypted
files in the bucket with more than one key. If \fIcurrent-key-id\fR is a file-
based key, \fB--in-key\fR must be specified. Otherwise, the user will be 
prompted for a password. The newly-generated key for \fInew-key-id\fR will be 
stored in a file if \fB--out-key\fR is specified.

.TP
.BI "change " "key-id"
Change the password or file key used to access the specified volume key. This
does not change the underlying volume key; it only changes the key file or
password used to unlock it. With no options, the user will be prompted for the
current key password and a new key password. With both \fB--in-key\fR and
\fB--out-key\fR specified, a new key file will be generated. If \fB--in-key\fR
is specified but \fB--out-key\fR is not, the user will be prompted for a new
password. This will become the new key password (i.e., key file access will no
longer be possible). If \fB--out-key\fR is specified but \fB--in-key\fR is not,
the user will be prompted for the current password but not a new password --
the key will be written to \fIpath\fR, and the key switches from password-based
access to key file access.

.TP
.BI "delete " "key-id"
Delete the specified volume key. If \fIkey-id\fR refers to the last key, any
encrypted objects in the bucket will become permanently inaccessible. The
\fB--in-key\fR and \fB--out-key\fR options are not valid with this command.

.SH OPTIONS
.TP
.BI "-c | --config-file " path
Read configuration from \fIpath\fR rather than the default paths. This file is
described in \fB__PACKAGE_NAME__.conf\fR(5).

.TP
.BI "-i | --in-key " path
Read volume key from \fIpath\fR instead of prompting for a password.

.TP
.BI "-o | --out-key " path
Write volume key to \fIpath\fR instead of prompting for a password.

.SH EXAMPLES
Generating a new volume key, using password-prompt mode:

.RS
\fB__PACKAGE_NAME___vol_key\fR generate main_key
.RE

Generating a new volume key, using key file access:

.RS
\fB__PACKAGE_NAME___vol_key\fR --out-key ~/.__PACKAGE_NAME__/bucket-0.vk generate main_key
.RE

Switching "main_key" from password prompting to key files:

.RS
\fB__PACKAGE_NAME___vol_key\fR --out-key ~/.__PACKAGE_NAME__/bucket-0.vk change main_key
.RE

Switching "main_key" from key files to password prompts:

.RS
\fB__PACKAGE_NAME___vol_key\fR --in-key ~/.__PACKAGE_NAME__/bucket-0.vk change main_key
.RE

Regenerating a key file for "main_key":

.RS
mv ~/.__PACKAGE_NAME__/bucket-0.vk ~/.__PACKAGE_NAME__/bucket-0.vk.old # save a copy in case the change fails

\fB__PACKAGE_NAME___vol_key\fR --in-key ~/.__PACKAGE_NAME__/bucket-0.vk.old --out-key ~/.__PACKAGE_NAME__/bucket-0.vk change main_key
.RE

Changing passwords for "main_key":

.RS
\fB__PACKAGE_NAME___vol_key\fR change main_key
.RE

Granting access with a second password-based key:

.RS
\fB__PACKAGE_NAME___vol_key\fR clone main_key new_pw_key
.RE

Granting access with a file-based key:

.RS
\fB__PACKAGE_NAME___vol_key\fR --out-key ~/.__PACKAGE_NAME__/bucket-0-new.vk clone main_key new_file_key
.RE

.SH AUTHORS
Tarick Bedeir <tarick@bedeir.com>

.SH SEE ALSO
\fB__PACKAGE_NAME__\fR(1), \fB__PACKAGE_NAME__.conf\fR(5)
